<a href="https://github.com/socketstream/socketstream/edit/master/src/docs/tutorials/en/how_it_works.ngdoc" class="improve-docs"><i class="icon-edit"> </i>Improve this doc</a><h1><code ng:non-bindable=""></code>
<div><span class="hint"></span>
</div>
</h1>
<div><div class="how-it-works-page"><h2 id="how-does-it-work">How does it work?</h2>
<p>SocketStream sends all the static HTML, CSS and client-side code your app needs the first time a user visits your site (all automatically compressed in <code>production</code> mode).</p>
<p>From then on all application data is sent and received via the websocket (or websocket fallbacks), instantly established when the client connects and automatically re-established if broken. Normally this will be in <a href="https://github.com/socketstream/socketstream/blob/master/doc/guide/en/rpc_responder.md">JSON RPC</a> format, but SocketStream 0.3 allows you to use different Request Responders (message handlers) depending upon the task at hand.</p>
<p>All this means no more connection latency, HTTP header overhead, polling, or clunky AJAX. Just true bi-directional, asynchronous, &#39;streaming&#39; communication between client and server.</p>
<h4 id="how-does-it-work_what-can-i-create-with-it">What can I create with it?</h4>
<p>SocketStream is a perfect fit for all manner of modern applications which require realtime data (chat, stock trading, location monitoring, analytics, etc). It&#39;s also a great platform for building realtime HTML5 games. </p>
<p>However, it would make a poor choice for a blog or other content-rich site which requires unique URLs for search engine optimization.</p>
<p>More code examples to follow.</p>
<h4 id="how-does-it-work_example-1-basic-rpc">Example 1: Basic RPC</h4>
<p>SocketStream 0.3 supports multiple ways to send messages to and from the server. The most common of which, JSON-over-RPC, is included by default. An RPC call can be invoked on the server by calling <code>ss.rpc()</code> in the browser.</p>
<p>For example, let&#39;s write a simple server-side function which squares a number:</p>
<pre><code class="lang-javascript">// in /server/rpc/app.js
exports.actions = function(req, res, ss){

  // return list of actions which can be called publicly
  return {

    square: function(number){
      res(number * number);
    }

  }
}
</code></pre>
<p>Restart the server and then invoke this function from the browser&#39;s command line:</p>
<pre><code class="lang-javascript">ss.rpc(&#39;app.square&#39;, 25)
</code></pre>
<p>You&#39;ll see the answer <code>625</code> logged to the console by default. The eagle-eyed among you will notice <code>ss.rpc(&#39;app.square&#39;, 25)</code> actually returned <code>undefined</code>. That&#39;s fine. We&#39;re only interested in the asynchronous response sent from the server once it has processed your request.</p>
<p>You may be wondering why <code>app.square</code>? Because we&#39;re invoking the <code>square</code> action/function in the <code>app.js</code> file. If you had written a <code>resize</code> action in <code>/server/rpc/image/processor.js</code> you&#39;d call it with <code>ss.rpc(&#39;image.processor.resize&#39;)</code>. This naming convention allows you to create as many sub-directories as you wish to organize your code.</p>
<p>Now let&#39;s write some code in the client to do more with this response:</p>
<pre><code class="lang-javascript">// client/code/app/demo.js

// define the number to square (vars are local to this file by default)
var number = 25;

ss.rpc(&#39;app.square&#39;, number, function(response){
  alert(number + &#39; squared is &#39; + response);
});
</code></pre>
<p>Once you save the file, the browser will automatically reload and you&#39;ll see an alert box popup with the following:</p>
<pre><code>25 squared is 625
</code></pre><p>More examples coming soon!</p>
</div></div>
